Join us Tuesday, August 11, 2015 in Petaluma at 6pm for a round table discussion on API/software authoring environments. Topics may include discussions around the effective use of lightweight environments such as Google Docs and Wikis, or how (or if) certain authoring environments are more suited to specific types of APIs.
Anne Gentle (www.justwriteclick.com / @annegentle) and Tom Johnson (www.idratherbewriting.com / @tomjohnson) have agreed to join in remotely to offer their perspectives and experience, but this is a round table, so we look forward to input from all!
Audio stream (1.5 hours) or download 60MB ZIP.
Chat log from the discussion. Scroll down for many links and references!
Who has seen a successful implementation of a lightweight or ultra lightweight authoring environment for knowledge sharing, training, and possibly external facing documentation, with photo illustrated work instructions for detailed hardware fabrication/testing/assembly? For example, team of 13 core engineers, up to 60 contributors.
What did this environment look like, and what did it take to keep it good? Did you need FT writers? How many/skillsets/task division?
In particular, what would a successful implementation of Google Docs look like?
Has anyone had to do REMEDIAL work in an environment where this wasn’t set up but now needs to be?
Do these environments ever actually run themselves, as some sponsors seem to believe they should?
(I know a bit off topic from API… but principles may still apply)
I think auto-generators such as Doxygen and Javadoc are essential for the reference material. But what I’m always looking for is a useful way to tie/hyperlink a reference topic to related User’s/Developer’s Guide info that is typically authored outside of Doxygen/Javadoc. Although one can use Markdown and extra (typically .page in Doxygen) files to hold non-reference material that gets included in the Doxygen/Javadoc output, these autogenerators aren’t very good authoring environments for that sort of info and for the more detailed/complex formatting that’s often desired.
I’m just starting to look into Breathe and Sphinx, so if anyone is using those tools I’d love to hear about it!
Thanks,
-Monique Semp