Discussion of what to do for the "info" link in the service specification:
Summary
We've decided that it makes the most sense to use the central Atlassian wiki. We would require that every official spec have a Wiki page with some required fields:
- Why would someone choose this tool?
- What are the primary features?
- A short (5-7 minute) demo of the key features
- NDS projects using this technology
- Related links.
The "info" link in the service spec will take users to the wiki page.
Analysis
Use a Readme
- Require every user to include a readme with their service PR following a certain template
Pros:
- Everything is in the ndslabs-spec repo
Cons:
- Editing requires PR
- Developer centric
Use the Github wiki
- By default, restricted to users with push permissions
- Can be changed to allow any Github user
- Fork/PR strategy can use a separate wiki repository with the actual wiki repo as upstream
Pros:
- Everything is centralized in Git
- Can support PR model, but not required
- Can allow true wiki-style editing (not so formal as requiring a PR) if we want
Cons:
- Wiki is separate from Repo.
- Developer centric
Use the NDS wiki
Pros:
- Makes use of the Atlassian wiki
- Nice central repo for non-developer types
Cons
- Requires NDS user account