#1 API documentation practices
- Many of us will be coming from the API documentation workshop the previous day. Let’s have a session to discuss and share what we learned.
Scribe: Margaret Spell
- Session to discuss what we learned in the API doc session. Suggestion on how to come up with info on what to do next—follow up from class yesterday.
- Code samples under source control? AWL(?), Swagger.
- Question on whether API doc can be automated when code is changed?
- Also comment on setting up documentation server for API docs. How would it be maintained in consideration of different versions? Build version in URL to handle version. Interest in automation of API docs in general, automation tools also. Even programmers need good documentation experience. If we do the API docs well, we bring more value. API docs is a high-demand area. Can be complex and an area when can try to simplify. API docs constantly changing.
- Testing APIs
- Regarding Swagger, if the doc is interactive, is all content in secure database?
- May have been point of confusion from class yesterday. Concern is about having the documentation on a web site. Usually have an API key that applies only to your data. Need to consider how to allow users to test API. Set up test account and let users test in a test account so they don’t mess up their data while testing. Need a server or protections on the server for this purpose.
- API explorer = try it out. Plug in values and get response.
- Compared to hand crafted SOK on …. they equivalent.
- Thinking of how to create whole API doc solution
- Swagger- put some static site generator. Other tricks into this? Suggest API explorer
- Need an example to explain a more complex transaction. This is an area where more info would be good—the tools and techniques. Ask customers for examples of how they have used the software.
- Kind of a recipe. Can the entire sequence of API calls be automated? Then API Explorer could be built in as part of this process.
- Tools to help with construction of API docs.
- Postman is a way to construct a template of values you set up. Explore Postman as a getting-started tool. Swagger takes experience. With Postman collection, you can save changes.
- Challenge with understanding API docs is the language. Assumes a lot of programming knowledge.
- “Write the Docs” podcast with Postman founder. Can have a Pro.
- Engineers write collection, then use Publish option to build out the information. Can set up an environment with Postman.
- Postman can auto-generate in different languages: Java, etc. Postman founder says users like this.
- SOK is flip side of API component. That is part that is language specific. Brings libraries together to construct calls to API. SDK contains tools and documentation.
- Challenge with API doc—if you have to document for multiple languages, use different SDKs.
- APImatic – another tool for stuff related to APIs. Can use to convert from language to language, automate unit testing, etc
#2 Cyber security and the role of documentation
- One reason that cybersecurity is challenging is the complexity of the conversations about it in every area of society. Explaining things simply is complicated. Technical communicators have made complex information accessible to other fields. How can technical communicators apply skills that we already have to champion global cybersecurity?
Scribe: Hannah Wiltbank
- Take the time to read the books and learn the acronyms.
- There’s a good market, but it helps to have some awareness of the applicable standards.
- Any pharmacy has to be HIPAA.
- Policies: high level (“we have a strict password standard.”)
- Standards: “everyone must have a strong password, not stored anywhere, changed every 6 months.”
- Procedures: how to change your password.
- May also need to write about physical security, network security, or app security.
- Government facilities use a different layer stack than commercial.
- New European standards for breaches: GDPR. European auditors are called registrars. Audits are called surveillance.
- CISO: corporate information security officer
- General emergency preparedness also includes preparation for IT and security-related emergencies.
- HIPAA requires a business continuity plan, an emergency preparedness plan, and a disaster recovery plan.
- If you are aware of data security best practices, you can be a great asset as a tech writer.
- CISSP: certified information security services professional. Sources differ on how useful the certification is, but it has potential to increase your salary.
- If you attend security conferences, you become known within the security industry.
- SP800-53 is the NISTs general security standard.
- NIST is under FISMA: federal information security management authority.
- You can attend the RSA conference for free.
- For security projects, you often must work on site and on their computer.
#3 Video/Audio – When are they better than print?
Scribe: Laurie d’Armien
- Audio is more important than video
- Videos are great for context
- Strike(??) out text
- Video of(?) human factor verbal
- Record little videos and merge or long and snip.
- Apple video showing movie are in addition to words.
- Generic words, contextual video.
- First video?
- First audio? Do long audio
- Audacity open source
- How to freelance as a Technical Writer in the Bay Area. Finding clients; customers; pain points; How much to charge; Tips/advice, etc…
- Business setup: through agency or sole proprietorship/LLC
- On-site vs remote
Scribe: Iris Rodgers
- When you’re freelancing, you’ll have to sell yourself – find places to show your work and network extensively.
- Sell the quality of your work over the quantity. Don’t see what you do, sell that you solve problems.
- Why do you (participants) freelance or want to freelance?
- Has done before
- Likes the variety and flexibility
- Is an experienced tech person, “you don’t need to hold my hand”
- Freelancing makes economic/business sense
- Opportunities to learn new technologies
- Sell the quality of your work over the quantity
- Big companies will want freelancers to go, agencies vary between 1099 and W2 work. Small companies tend toward 1099.
- Finding clients:
- LinkedIn Pro
- Company posts
- Networking (This option can be slow – need to be persistent with your contacts)
- Direct relationship with hiring managers
- Staffing agencies (comes with pros and cons of using a “middle man”)
- How much to charge?
- 80k/year on a W2
- 160k/year as 1099, but this is a maximum
- You’re working 2000 hours, get paid for it.
- Freelancers, you are your own salesman and hiring manager.
- Don’t sell what you do, sell that you solve problems.
- Ask what the problem is or what the pain point is
- Address that problem.
- Be proactive.
- This is how you’ll get to a hiring manager before they even post the job.
- How do you estimate work?
- How long is the document
- Rule of thumb: 1 page = 1 day
- Scope of work is often underestimated by the manager, so you’ll have to walk the line between real estimation versus the estimation that gets you the job.
- You’ll need to gauge how realistic the particular manager is.
- How long is the document
- Advertising Methods (Getting Work)
- Write articles on LinkedIn
- On-site versus remote
- Remote work is harder to get than on-site
- Freelancers often do both.
#5 DITA, lightweight DITA, and markdown
- Can Markdown replace DITA (or other structured models) in techcomm?
- What problems in DITA does Markdown solve?
- What about Lightweight DITA, is that better or worse?
- LwDITA provides for Markdown and HTLML “flavors,” will you use those?
- Or, is this all just more craziness?
Scribe: Elaina C.
- DITA/Markdown are not mutually exclusive.
- Use them all to your benefit, and find ways to convert content (e.g. so you can let engineers keep using Markdown)
- Lightweight DITA will be a codified standard soon, and will only include about 40 content objects.
- Who’s using DITA vs. Markdown?
- Lots of DITA novices.
- DITA is more semantically structured than Markdown.
- Markdown has minimal structure, i.e. paragraph, list, but not “prerequisite paragraph” vs. “context paragraph.”
- <menu item>Settings</menu>
- Ex: Adding semantic tags like ‘command’ and ‘expected output’ which later allows Python script to execute commands, compared against expected output, and verify whether the documentation is correct.
- You can inject some structure into Markdown docs, but it complicates it so you are starting to mimic XML.
- Advantage of Markdown is that engineers use it, it’s compatible with github and their process.
- What’s Lightweight DITA for and all about?
- Problem: Engineers want to contibute with Markdown, TWs want to work with DITA.
- Lightweight DITA keeps only the minimum amount of semantic structure necessary. Not yet a fully baked standard!
- What are the common structures betweeen:
- Marketing procedures
- Tech Writers in engineer land
- Training teams
- Publishing tool would be able to output from any of your rouses (Markdown, XML, etc.)
- *No audio/video tags for DITA currently. Working on updating this, because important to so many and will be included in LW DITA.
- DITA is a standard, LW DITA WILL be.
- Usually, TWs are NOT using engineer-created docs in reality. It’s an input, but the job of the TW is to translate, decide what to include, etc.
- So how easy do we need to make it for engineers to contribute?
- Better use case is for things like RESTful API documentation – pull in docs from github to your authoring tool.
- Do Open Soure companies have a disadvantage?
Since not willing to pay TWs, they are most interested in lowering the barriers for the community to produce + contribute content.
- Traditional DITA: Task / Concept / Reference
- DITA 1.3 has more topic types for increased specialization; e.g. Troubleshooting
- (IxiaSoft) Internal/ External commenting on docs
- Compare DITA vs. Flare – a matter of scale. DITA better for bigger scale
- Do tools have good support for reviewers? Who needs to know the tool in order to comment, review, etc.
- Almost 700 objects in DITA – only 40 in Lightweight DITA
- Flavors of Markdown? Github is the winner. rST, proprietary
#6 Best practices for documentation navigation
- What best practices exist for documentation navigation?
- Should you implement progressive disclosure?
- Shortened navigation titles?
- How many levels before users tear their hair out?
- Do users even look at the sidebar?
- What are some examples of navigation sidebars that succeed and fail?
- Should you eliminate the navigation all together?
Scribe: Jessica Parsons
- Thinking about what no nav looks like is scary & interesting. This would be a good topic for next time!
- Search prevalence changes how people approach content.
- “It depends” – on product, on users, on goals.
- Shortened navigation text
- Visual and auditory
- Front-load important, distinguishing information
- Between & within items
- Action verbs at the start are helpful
- Don’t have two options that sound the same or are hard to distinguish.
- Searchable context
- How to have essentials be read by people
- Searching & jumping to one section, for example, safety warnings
- Long pages are searchable, and people are used to scrolling.
- How to have essentials be read by people
- “Time to Knowledge” – What is the quickest way to get the info I really need?
- What if we don’t tie nav to titles? Stub sections?
- Navigation can pose friction for readers, but also for writers.
- Section numbering:
- Good for technical reference material
- Not as friendly for consumer products
- Can be a nice waypoint, but it also assumes linearity
- What about no navigation?
- Chatbots: To replace or augment navigation?
- Search: What used to be the index
- Scannability is important
- TOC is nice to get an overview
- Expand all/collapse all is helpful
- Have TOC navigation, can search, kind of like a really long webpage in these ways
- Every Page is Page One?
- Lots of repeated content, because people don’t read front to back – they want all of the steps in one place.
- Links save repetition, but they’re a bigger hassle to read.
- How to make sure that people read safety warnings?
- Have people click a button and read a pop up to get to the next step