Where should documentation live?
holingpoon opened this issue · comments
I've been staring at some old documentation, and these pages are everywhere: On Confluence via Atlassian Cloud, on confluence.nypl, various Google Docs, etc. Our newest spot was to park the documentation on GitHub Wiki pages. Having a discussion with @nonword, he pointed out that the search function on the Wiki is broken. I was on the track of thought that maybe if we ever have to move our repos again somewhere else, we will lose the GitHub Wiki pages because it is specific to GitHub.
I have a suggestion: I think it'll make more sense to embed documentation as part of the repos, e.g. a doc or docs folder in the code repo, and park all our documentation written in MarkDown that is somehow outside of README. That way the file structure is vendor-agnostic, we also have a plus that most repo management vendors such as BitBucket and GitHub would parse MarkDown files.
I fully support this. Vendor agnosticism - plus Github clearly does not care about their Wikis. Perhaps a PR is in order to https://github.com/NYPL/engineering-general/blob/master/standards/documentation.md to specify what documentation MUST exist at the root level (e.g. README.md, LICENSE.md), and what documentation SHOULD/MUST live in docs/ (e.g. docs/extended-discussion-of-architectural-choices.md, docs/architectural-diagram.svg, docs/swagger.[version].json)
I agree, I fully support documentation to be 1) vendor agnostic 2) in markdown
Transfering Github Wiki's into the /documentation or /docs folders should be relatively easy.
I will note that some of our Node Web Apps use /docs for ESDOC documentation generation and typically it is not in source control. I propose the ability to use either or /docs or /documentation
CC: @holingpoon
I am happy with docs living along with the application.
It's a shame that GH has invested so little in their wiki functionality considering how potentially powerful it is that the wiki itself, is also a clone-able git repo.
Love this idea.
This issue is quite old, over a year. Closing, with a tag of archived. @holingpoon, FYI!