Breaking into API Documentation
- 2 main types of API are web & platform
- Start with REST, says Peter Gruenbaum because it’s about the understanding of data.
- How much do I have to know?
- Peter says there is a controversy about this, you have to really like it first.
- If the hiring manager says you must write vs. understand sample code & test run it.
- If devs or API writes itself, ask if docs are meeting needs
- Who is audience?
- Learn in community colleges
- Languages – in 2008, Java
- Latest rise is mobile, so SDK for
- Objective C (larger projects to expense/maintain), Swift
- Consider if you like developers, can relate & see goals.
- Re. usability, understand their needs, to be successful.
- Can be literal & bad[??]
- myopic commit[??]
- With IOT etc., done them APIs like a new field & different world.
- Lot of demand
- What about automation?
- Question is enter spec w/ details that RAML spits
- then conceptual & procedures – software can only do so much
- Devs don’t want to write prose
- English is code, w/ fuzzy meaning – complicated code.
- People say there’s open source that needs github & sourceforge, see what [??] you
- e.g. music, find a project music & incubators[??]
- [___?] & improve, often in markdown
- y-combinator help needed – sample[?] open source tech writers needed
- markdown 5-6 flavors – developers like markdown
- add markdown [__?]
- if banking or H.R. & did doc in that, send[?] that realm
- Create a mobile app SDK
- Don’t have to create an something just document it
- There’s little market out there to directly learn API
- & Tom Johnson’s – Sarah Maddox
Scoping a Hot Mess
It used to be that there were tech pubs managers, or product managers, who actually understood how docs were made and why they were important. Lately, however, I’ve been called into teams where everyone agreed that things were confusing, but nobody knew what to do about it. No budget and no clear deliverables. They seemed to be looking for a “free” fantasy fix where the writer would simultaneously tell what deliverables they needed, and reassure them that these could be had practically for free, overnight.
Let’s discuss how to tell a good client form a waste of time, and how to say “no” without sounding unprofessional.
The technical writer, who authored this topic also asked the group what happens when you can’t say no?
If you do take the job, you may need to reset a lot of the stakeholders expectations from marketing, product management, engineering, and your manager.
This situation could be manageable in larger companies like Cisco where there are tools and the systems in place, for example, a content management system that can help you manage the situation.
How to Scope the Project
- One writer talked about his extensive experience with HIPPA and how he encountered a small start-up company, which was clueless about the documentation they needed to be HIPPA compliant.
Ask the Right Questions
- Drawing on his extensive experience, he was able to ask several pertinent questions such as:
- How do you protect HIPPA data?
- Do you have a disaster discovery plan?
- Do you have a business plan?
- Do you have a data plan?
- Do you have firewalls?
- Do you have strong passwords?
- What do you need done at once?
- Put all of the things on a spreadsheet to track all of the necessary documentation.
- Who is the single point of accountability for the different documents?
- Ask the customer the right questions. What do you have, what do you need?
- Are you willing to spend any money? Figure out what the budget is. Perhaps learn sales techniques by offering three different solutions with prices.
- What are the pain points?
- May need to reset the client’s expectations.
- Leverage relevant experience that you have previous companies.
- Add some structure, perhaps a spreadsheet to track the deliverables. Figure out what needs to get done, first.
- Identify whether the problem can be satisfied through the technical writer or not?
- Leverage what do similar companies do in the same situation.
- Get a commitment to the project to the budget.
- Charge a higher rate, so that the people will respect you, or use this as a strategy for a company where you don’t want to work for them.
- Calculate your general rate in relationship to the risk: professional, or lack of desirability.
- Ask to see the existing documentation.
- Get customers by word of mouth.
- Be comfortable and have a particular niche so that you can come in and scope out the project accordingly.
- Do a doc plan.
Writers and product usability
- Writers often find usability issues, extensive docs can be a red flag for bad design.
- We can help our voices to be heard by enlisting PM, support team, UX designers & building a rapport with engineers.
- We can back up our observations with site visits, usability tests, going through support tickets, monitoring Slack or Twitter channels.
- We thought that the bullet “Identifying Dovetailing Issues” could use some usability help. [??]
Usability is part of our jobs.
- Are we the canary in the coal mine? Do we suffer from bad design?
The need to write extensive documentation is a red flag for usability issues.
Getting the tech writer into the design process can find issues before it’s too late.
- How do we determine if a product is usable? UX team is often responsible.
- It can be hard to get their time/attention, sometimes they don’t like working with tech writers because it takes extra time.
- We might have the same goals but have different approaches to the solution.
- How do writers get their voices heard?
- Build a rapport with engineers
- Go to PM
- Suggest a workaround
- Speak up a scrum team meetings
- Help engineers with something they need
- How to back up your own observations?
- Pick your battles, get the PM on your side
- Site visits can pack a lot of learning into a short time about how customers interact with the product
- Usability tests can be humbling and eye-opening
- Support engineers on the phone with customers can point out problem areas
- Look through support tickets with developers
- Documentation Slack channel, Twitter channel
- Customer surveys are one of limited usefulness & can be hard to write well
- “Dovetailing” issues – identifying them
- The question needs usability work!
- Is usability different between different types of writing (UI vs. API vs. ??)
- For APIs, naming is important, butt engineers often don’t consider that
- Naming APIs are notoriously bad
Instructional Design for tech writers
- They overlap, but is in 3 or 4 dimensional. TW is 2 dimensional
- ID has opportunities for interaction, discovery, experimental
- What writers need to know: Be willing to go beyond text, use of video. Knowledge of UX design.
- ID has scaffolding: Layering
Tech writing is content [????], assumes knowledge of what to do; ID is customizable opportunity to explore.
Learning is about change in behavior that is measurable.
Efficient content review tools
- Scary that we’re still having this conversation in 2017. No one-size-fits-all review process.
- Tons of tools out there, driven by content creation tools/processes. Got to get a system that works with process you have.
- Google Docs common (not perfect) group review tool.
- Also word track changes and PDF
- Google docs for review (not perfect, pretty common)
- SAP – content in HTML5. People can review one central document at same time
- PDF Server – review one central PDF doc at the same time.
- Word track changes – the author still has to consolidate
- Use Confluence – edit same wiki page. Effective for small documents.
- Salesforce has review tool. Reviewers can review the same doc at same time.
- How secure is Google docs?
- Box.com another tool.
- Egnyte – cloud-based repository, fairly secure.
- Reviewing out of your firewall. Work[???] the [??] out of it and have reviewers sign NDA
- Reviewboard. GIT + Reviewboard + Docbook for PDF output. Might be too complex for non-technical reviewers.
- Github has a review capability.
- Scary that we’re still having this conversation in 2017.
- SDL web-based review.
- Grammerly – great for free plugin, spellcheck and grammar check in real-time.
- Grammark[??] – open source
- Stylereviewer[??] – paid tool, software, “Bark”[?], Index. How tough are your sentences to get through. This highlights, doesn’t correct.
- Hemmingway[??] similar tool.
- Plugin (Jost) for WordPress, gives you SEO rating.
- Editors – an endangered species [??], even though they are critical for consistency.
Document architectures, data modeling, reuse strategies
Wide variety of experiences with DITA and non-dita architecting.
easyDITA rep: Reuse versus rewrite, especially for larger, enterprise companies. more than 50% – then reuse. If less than 50% is reusable, then they rewrite.Too much management. Large containers for a lot of reusable pieces. Reuse has a lot of overhead. it’s great, but it takes work. Mechanics are straightforward, but it’s over time that’s challenging. Cost-benefit analysis
Context changes!!! You can’t be as narrow, you must be far more broad – write with reuse in mind. Can’t write specific to that thing. If it’s so general that it’s not usable, then be specific and don’t bother with reuse. always go in with a plan, don’t just jump in. Migrating to DITA must be very well planned and well structured.
From a reuse strategies perspective, planning is invaluable.
- Write content thinking that it could be reused (not by you, just by anyone).
- not too much details or specificity, at least use variables.
- For content to be reusable, it needs to be structured in such a way that component a and component b are comparable/structured the same.
- Writing style has to jive together.
- Does that content exist? You can’t reuse something when you can’t find it or don’t know that it exists.
- EXTENSIVE PLANNING
- Annotated topic lists. These are the topics/tasks that we need to write. Check repository line by line.
What do we define as reuse?
- Is it publishing to multiple output channels or is it reusing across different product lines/doc sets/dita maps?
- Reusing commonly used topics. warehouse topics – i.e. note warehouse is one large topic that contains all of the commonly (10+) reused notes (i.e. safety warnings). Want reusable content? Check that warehouse.
Every tool has a warehouse, library, or collection topic. What granularity will your warehouse go down to? Are you willing to go down to a single step for reuse or do you want larger pieces?
Some people have really redundant or cumbersome reuse policies. Reusing stuff that maybe shouldn’t be reused. Granularity/Time/Cost.
Overhead of localization: you definitely don’t want to be branching and then creating separate topics that are somewhat different. You just continue to have impact on expense. People justify most of their dita implementations because of the cost of translation. But that is also the danger of granularity. Messed up things for the translators to the point where your content can’t be salvaged.
You often have a certain level of specificity that is truly unnecessary.Taking that kind of content out makes reuse more feasible. What can you pull out of content that would keep you from reusing the larger piece?
the type of reuse is another thing that is important. There’s a difference in the term of outputs, but what about things like conditional text? One document can generate multiple manuals with conditional text and variable. A lot of people go into dita, and thinking that they understand conditions and can use them this way, and it becomes impossible to deal with those topics.
The point of reuse is not to create a smaller number of topics. The point is to reuse things in a way that is planned and intentional. Develop a reuse strategy for conditions. If my topic has more than 50% conditions, you should seek another solution. Multiple topics with a small piece from warehouse and the rest that was conditional is now separated out.
The problem with that is that there is far too many rules about conditional pieces. I’m just going to condition this out – you know but how do you communicate all of these rules to your team members. It makes it easier for everyone.
and then you have concerns about version control, and everything gets even more complicated. Reused, then version change, reused again, version change. so, which deliverables are pulling from which version? Everything gets jacked up. How do you manage that? Versioning is why people start using content management systems over DITA.
the key to reuse is TRUST. they don’t trust that you won’t change it and then it won’t apply to them anymore. Does your CMS have the user be required to explicitly agree to switch versions? Branch/merge capabilities – or lack thereof – is a big concern. Use Git – but not all of the versions.
Newbies getting best practices info -hooray!
The writing has to be the same style from different writers. If you’re reusing something three years later, and your voice and style guide changed, you have to end up rewriting it anyway. Be intense with your style guides.
Reuse: if it’s not wrong, don’t fix it? Little nuances – back off, because it’s screwing up the content reuse paradigm. Content reuse is changing the nature of authorship. Give up on your ego?
People often get heads down in their own lanes. Less collaboration leads to less consistency. Add training and oversight. When you’re to the point of needing to develop your terminology, etc. you need to have someone who words is their deal. then editors can sometimes take over some information architecture duties. Same type of thing, making sure everything is consistent and following the correct forms.
In order to be able to reuse content, the architecture is really important. We all get messed up using different types of tables, elements, etc. bars reuse. Have to plan ahead – style guide for which elements you use for what and in which situations.
Information architecture work – what are the rules dita side for how your content is structured? Do you have consistent chapters or sections? Break that down even further. What happens in each individual chapter or section – TOC or introduction? topics? etc? How do we express each type of thing in which element
Create an Information Log – which elements, linking, metadata strategies.
People think that moving to DITA or a new architecture – they don’t give it a realistic timeline. Conversion is only a small part of the process. The thing that you really have to consider when moving to a new system is that you’re changing your processes, your content strategy, the architecture – everything you did in your old system – you’re not doing that anymore. You’re doing things differently now – that’s not a 3 month thing. A typical DITA implementation will take 10 to 15 months. DO YOUR ARCHITECTURE BEFORE YOU CHOOSE A TOOL. This will also help you with requirements/acceptance criteria when choosing a vendor. If you don’t support XYZ, we can’t have a successful partnership. What’s a deal breaker vs. a delighter?
You have to rework all of your content for style and structure when migrating. You can’t convert and then go back and fix it later. You can’t deal with something ‘someday’. Migration is a great way to discover what you can reuse and maybe what you should have at some point reused content. This is a time to evaluate your existing content as well. That’s when you can also use all of those strategies that you planned out before selecting a vendor.
Garbage in, garbage out. You have to migrate CORRECTLY and WELL. Good implementations take so long because you realize when you’re doing your topics how your content is and should be modeled. How do you clean it up, create warehousing topics, rebuilding as you go. If you don’t, you’ll always be catching up. Sometimes your really old stuff can just be left behind – is it worth the time to migrate content that’s not so great? legacy content can sometimes just go.
Other take: only warehouse boilerplate language. Say your software is being updated. There have been 3 releases since you last wrote the content and you need to document each rls separately. You’re using them once in features and once in RN. Lengthier content – if you can reuse it – DO. Long content is expensive, so try out topic level reuse, rather than steps. the more steps, the less likely context is going to trash your task.
Other take: the minute something is reused, it should become a warehouse topic. Never reuse content from another topic. If you reuse it, it immediately becomes a warehouse topic. This way you can avoid spaghetti code.
New dita versions – new reuses. Do you retroactively implement? Set up some policies. Don’t get too locked into what you know. A new feature may come and then you ask where has this been all my life – how can we use new feature on our older content. Decisions that you make today may need to be reworked later. Process maturity models really emphasize adaptability to change – it’s a sign of a mature org.
If a large body of material gets carried version to version, and you only edit like 20%, it’s nice to be able to reuse those larger pieces.
If you think that you’re not getting enough of the benefit of reuse, you may not have started with a good metadata strategy, or any metadata at all. if you can’t find your material in your repository, you can’t reuse it. If you’re early on in the process, it’s okay to change your mind about reuse strategies, but you need to have at least something for metadata. It leads to a retroactive mess.
When you’re architecting how you’ll be able to find things, do you depend on metadata or folder structure?
Define metadata broadly!