Documentation guidelines for authors needed

[pzermoglio]

[Some of the comments below come from issues that @ArthurChapman, @tucotuco, and myself, have found / were wondering about as we were updating some of the documentation)

Authors reviewing/updating/producing documentation require at least a basic guideline on how to do it, what to provide back to the documentation panel (one of who's responsibility is to "Review drafts and provide comments back to authors", see https://github.com/gbif/doc-documentation-guidelines/issues/1), in which format, etc. Such guidelines could include (not exhaustive):

• File format. Are authors supposed to write in Ascii docs, as suggested in the doc-template repository.

  • If yes, is there a recommended software, Notepad++ or some other equivalent text editor, Ruby API, ASCIIDoc.Live, etc. (Note that none of these allow for collaborative authoring/editing etc. as they don't (easily) allow comments, edit tracking). (many other issues here related with how to deal with certain types of info/formats in working with ascii docs, not putting details until knowing whether the answer is indeed yes.
  • If no, which formats are they expected to provide? word docs, google docs? pdfs?

• Related, should they provide each of the ascii doc files listed in the doc-template repository as separate files? as adoc?

• Images/tables. Should they be provided separately? Format? Size? Metadata (including licence)? Are we following any known publisher's policy in this? Should it be a requirement that e.g., when software captions are included those captions match the language of the documentation? or make it explicit.

• References. Preferred style?

• If someone else (other than the authors, could be tech person/helpdesk/editorialPanel or a combo of all of those) is dealing with converting to ascii docs, are there features in the documentation that authors should point out as being important for the document itself and that should be kept as such? (this, thinking that depending on the tool used to convert doc to adoc, is simpler or more complicated to keep some formatting).

• Which will be the possible licences that the documentation would be under...? restrictions?

[dschigel]

Hello people. As @kcopas wrote before, @laurarussell may not be available at the moment to reply. My recommendation, in Laura's absence, would be to focus on content in the environment that you are comfortable to work with, and do not worry about formats etc. for now. I read ToRs that our panel it to make sure that i) right guides are being created and ii) content is up to GBIF standard, which is not too far from editorial work for the journals. The rest are details and we are not asked to set the entire publishing house here - please check the EP resposibilities, and let us wait for Laura to comment on those.

[pzermoglio]

@dschigel Agreed on what to do in the meantime with the particular documents, yet these seem issues to address at some point, capturing them as such in here with that intention, as agreed on email. Could you point us to the "GBIF standard" that you mention? I haven't been able to find any such document available, not to the public at least... Thanks!

[kcopas]

Taking the above in, recognizing that the responses are in many/most/all cases first drafts toward the necessary documentation…

File format

Are authors supposed to write in Ascii docs, as suggested in the doc-template repository.

Documents will be published in adoc format, so ideally, yes, authors will help us get them there. When it's complete and up-to-date, the doc-template repository should both remove much of the guesswork and provide working if brief examples as to how authors can help us prepare the documentation.

From a practical point of view, though, the reason we will be working with specific authors is because they bring expertise to the specific content they are assigned. And if someone's really struggling with AsciiDoc, we don't want that to be an obstacle for completing assignments. We will take this issue up as and when needed.

Neither do we need to dictate how authors start work. Do documents need to be in AsciiDoc from the start? No. But we will need to work with authors to put documents into the format prior to putting them out for public review—this is an absolute prerequisite.

Related, should they provide each of the ascii doc files listed in the doc-template repository as separate files? as adoc?

As for recommended software, AsciiDoctor recommends a 'modern text editor', which probably extends beyond the tools listed there. Many text editors do support live preview/syntax highlighting of AsciiDoc, though it sometimes exists as a non-default option that needs to be toggled on. I use Adobe Brackets, for example, and simply needed to install an extension

Although you are correct that

none of these allow for collaborative authoring/editing etc. as they don't (easily) allow comments, edit tracking

—that's what the GitHub-based system is intended to support.

Images/tables Yes, provided separately. Stored in the /img folder as (will be?) in the template. Format based on image type—pngs and/or jpgs. No specific suggestions on size, yet. High-res source images should be stored in an /img/_src directory. Metadata would include caption, source, and licence, as and where necessary.

And yes, any included captions should match the language of the documentation (they'll be available to translators through the standard translation file).

For complicated figures, although we've been investigating the feasibility of producing, say, SVG files that could be translated, we're more likely to (work with authors to) work them up in a proper tool (e.g. Adobe InDesign or Illustrator) and create different versions with translated text.

References As mentioned elsewhere, style is best described as Harvard minimalist.

If we're talking about references to other things, hyperlinks to persistent identifiers would be best (e.g. links to DOIs). If anyone feels the need to prepare a bibliography, we'll combine the two above, but I'd really prefer not to use foot- or endnotes if at all possible.

Licences I'll be preparing a recommendation for the editorial panel on this topic for consideration in its first meeting ;-)