Improve this document link/icon/nav item
Closed this issue · 7 comments
@MattBlissett what I'd like to do is have a document called 'CONTRIBUTING.en.adoc' in each document's directory and add a link to it in the top of the nav with the label 'Improve this document'. I have two magic wand icons saved in ../img/_src in this repo, one azure blue and one GBIF green. Use whichever works best (wish it was blue, but the consistent use of green might be better).
This is a global change, one I'd like to retrofit into the existing repos we have in development. Hoping that having it be a separate file doesn't make for any unpleasantness. The only place where I need to link to it from the text is in the document guidelines repo.
This is one approach: the 'CONTRIBUTING' file is rendered to a webpage, without a table of contents. It would be translatable and updatable as usual, and is linked from each document: http://mb.gbif.org/documents/doc-sensitive-species-best-practices/en/
If, instead, the file is copied into each repository, it will need updating with any changes and translations in every repository.
Another option would be to integrate it directly into the Documentation Guidelines and link to the relevant section/chapter. I think we are pushing the boundary between a book/article and documentation here, with everything on a single HTML page.
I like the single page and single translation. How much of a hassle is the config on that?
Easiest is if it were a completely separate document, in which case it would appear at something like https://docs.gbif.org/contributing/en/.
Alternatively, it could be a second "page" of the Documentation Guidelines, in which case it would be something like https://docs.gbif.org/documentation-guidelines/en/contributing. This would need some fiddling to have second "pages" in documents.
Got it. My inclination is for the single repo. Let's set it up for translation from the get-go, maybe.
I will need a translation for "Improve this document" in Spanish, French, Portuguese and simplified Chinese.
Then see https://docs.gbif-uat.org/template/, and https://docs.gbif-uat.org/contributing/ for the contribution document. The contribution document will need to be released for the link above the TOC to work.
Let's machine translate to get this going, and I'll ask for improvements from our translators:
FR: Améliorez ce document
ES: Mejora este documento
PT: Melhore este documento
ZH: 完善这份文件