![]() We also have a style guide available on another page. Limit the length of a single topic to a single page, preferably less.Ideally, follow each heading with a concise short description. Include Prerequisites, Result, Related Links, and Post Requisites sections as appropriate.Keep the steps concise and, when needed, link to background concept material.(Which is why we title task topics like steps.).When a step has too many substeps, create a separate task topic, and link to it.Title a task topic as if it were a step.Create substeps, as appropriate, but limit to ~nine steps.Limit each ordered list to nine steps, more or less (less is more).Reference and concept topics may be presented differently.Explain task topics step-by-step in an ordered list.Prefer task topics to concept and reference tasks.Speak directly to the reader in an active voice.Here’s my DITA task topic for writing help topics: It’s also easy to reuse the same topic in multiple ditamaps, or multiple times in the same ditamap. Since DITA separates semantics from presentation, it’s easy to use the same source to create both Webhelp and PDFs. (Likewise, Salesforce uses DITA to compose its mammoth array of documentation.)ĭITA – The Static Site Generator for Professional Technical Writers Contenders here would include Kirby, Jekyll, DITA Open Toolkit, among many, many others. A flat-file CMS or static site generator that uses formats like Markdown or DITA to generate your help site. ![]() Some CMS products have built-in facilities for bringing out a new version of your content or plugins that generate a static web site. A dynamic Content Management System ( CMS), like Confluence, Umbraco, or Keystone, among a thousand others. ![]() Likewise, before updating for a new release, you could copy the existing document, and hide those nasty Google Docs URLs behind friendly names, using web-server aliases that can be updated as new versions roll out. (Salesforce uses this approach with its Release Notes PDFs.) When a new release rolls out, you update the aliases to point to the latest and greatest. During development, you could be publishing updated copies under new file names. Given a web server with aliasing capability (see part 2), you can link the aliases to a suite of PDF documents. In part 1 and part 2, we looked at configuring Salesforce and configuring your own web server - but what do you put on your own web server?Īnd - this is important - how do you coordinate rolling out new help content with rolling out a new version of your application? Salesforce is unopinionated as to what you yourself use to create your own help site.
0 Comments
Leave a Reply. |
Details
AuthorWrite something about yourself. No need to be fancy, just an overview. ArchivesCategories |