-
Notifications
You must be signed in to change notification settings - Fork 1
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Documentation guidelines for authors needed #2
Comments
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. |
@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. |
Taking the above in, recognizing that the responses are in many/most/all cases first drafts toward the necessary documentation… File format
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
—that's what the GitHub-based system is intended to support. Images/tables 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 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 |
[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 #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.
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.
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?
The text was updated successfully, but these errors were encountered: