Session 1 Topics For Discussion
- Documenting APIs
- Scripting FrameMaker
- Keeping up with industry trends
- HTML5
- Metadata and categorization strategies
- Job search techniques, leveraging LinkedIn, recruiters, portfolios
1. Documenting APIs
Scribe: Karen Aidi
Facilitator: Fred Jacobson
Top Takeaways:
- Knowing a programming language is virtually essential (Start with Python or an easy lang)
- Know the industry and the domain language to communicate effectively
- Look at Web APIs – particularly REST APIs – look at Twitter and Flickr APIs as documentation models
- Using your language write a small code snippet
- Account for the range of experience of your audience
Notes:
Fred started out with asking what the participants wanted to get out of the session. Most were interested in how to break into API technical writing. There were many themes and questions throughout this session:
- What is API documentation?
- What is good API documentation?
- Do I have to be a programmer to write API documentation?
- Who writes the code samples?
- What is the difference between a human writing the API documentation versus “autodoc” reference manuals?
- How do I get started as an API writer?
There was a general acknowledgement that there are many API writing jobs. And, these jobs want a person to know several programming languages: such as Java, JavaScript, PHP, C++, Python, just to name a few. A lot of job descriptions seem to reference REST APIs, so those seem to be very much in demand right now.
What is API documentation?
There were both newcomers to documenting APIs as well as experienced API writers in the group. Newcomers to documenting APIs, asked for a brief definition of what an API is. An API defines how two pieces of software talk with each other. There are many types of APIs: APIs to extend an existing software system as well as Web APIs.
Sarah Maddox gave two examples of Web Service APIs: Flickr and Twitter. As an example, she mentioned that a WordPress blog uses the Twitter API when the blog includes a twitter feed on a web page.
A participant asked: does a (web) service mean the same as an API? No, it doesn’t. There are different types of APIs: web services APIs might be REST APIs or other APIs, while some APIs may extend an existing system by using a Java API.
What is good API documentation?
Tactics for producing good API documentation include: interviewing project managers, internal users, and other users besides just the engineers, and looking at marketing documentation to get an overview.
In an agile environment, look at the user stories, which will help the writer with use cases. Learn about the development process by observing engineering in your own company.
Do I have to be a programmer to write API documentation?
Do you need to be a programmer (coder) to write API documentation? Not necessarily, but writers should know what programming is, should learn a programming language, and experiment with code snippets themselves. Fred mentioned that a good programming language to start with is Python.
To get some practical experience, one participant recommended using Postman,
an extension to Chrome. You can go from Trjullio or Twitter and start making some calls with Postman.
Who writes the code samples?
Does the writer write code samples or does the programmer write them? Yes and no and it could depend on the job.
One writer shared that he has never had to actually write the code samples. Usually, he leverages code from QA. Another tactic might be for the writer to create a story to provide a context for the examples throughout the documentation.
Programmers want to get their job done, so they love code samples that they can use. In some cases, the programmers will write the code samples, particularly, the more involved code samples.
What is the difference between a human writing the API documentation versus “autodoc” reference manuals?
Automatically generated or “autodoc” reference manuals are automatically generated from the code source. The programmer may write the first cut descriptions. However, the human still needs to be involved because there is a gap between the reference manual and the task that a programmer needs to perform. This is where writers can add a great deal of value. Auto-generated reference manuals may be laden with jargon or may not explain terms or pre-requisite tasks that are useful to all levels in the target audience.
How do I get started as an API writer?
How does one go from government type of work to API documentation? The analogy given was a car analogy. If you are in the left lane and you want to move into the right lane, you signal that you want to make a lane change, and you start to steer yourself in that direction. Find an API that you like, write some code, build an example, and then publish. Learn one language, learn the principles. What language to learn? Python was mentioned by Fred as a language to start learning.
How does one deal with intellectual property (proprietary API) versus public APIs or REST APIs?
Understand the audience. Use conditional text to prepare two different deliverables: one for an internal audience and one for an external audience.
2. Scripting FrameMaker
Scribe: Joanna Broadbeck
Top Takeaways:
- Scripting FrameMaker is used to automate repetitive task or tasks that must be performed across many files
- There are two methods for scripting. ExtendScript is a Javascript-based language provided by Adobe and is free. FrameScript is a 3rd party solution more similar to VB Script
- It isn’t easy to get started. There are several consultants available. See their websites, free samples
Notes:
What is it?
MIF-save in this format to go to older version, to get rid of errors, “MIF washing”
ExtendScript (in FM12) vs FrameScript
Scripts can do all things you can do manually, via script
Rick Quattro does scripting
You must know FrameMaker document model; scripts can read external file
Scott does FDK development
Where’s the good documentation? Adobe FM Scriptmaking Guile
Developer Portal.
Sec West Street Consulting – FDK developer that created many samples
Resource: Adobe FrameMaker Scripting Guide
Inter-application communications are possible FM<–>other adobe products
Script types: Notification scripts, startup scripts, etc
What would you use it for?
- Doc conversion and apply templates (you can make a map for that)
- Use scripts for automated formatting (anything you can do manually)
- Create PDFs (lots of books)
- Carpal Tunnel prevention!
- Reduce the time it takes to do repetitive activities
- Huge search/replace
- Master books (including books within books) – Leximation.com website has plug-ins, including free
- Apply tags to many files
- Restructuring docs based on styles to go into DITA
- Assigning attributes to conditions during a conversion
How much need is there for scripting FrameMaker? It’s not difficult, but … West Street Consulting = Russ Ward does sessions on scripting in various languages; Scott Prentice – just spoke about going from FM to DITA
Semi-related discussion: Companies are using Word again. Easy to record a script. if developers must edit, companies use word.
ExtendScript only works on Adobe products – Not for MS products
Download samples form West Street Consultants, Frame Gurus, Adobe Forums
3. Keeping up with industry trends
Scribe: Wendy Shaffer
Top Takeaways:
- Safari Books Online
- Slideshare
- Techwr-l list
- Conferences
- com
- Code Academy
Notes:
Self-teaching: safari books online
Slideshare is a great resource for presentations
industry trends: Writing style (Simplified Technical English), Mobile, Video, Social Media, Personalization, Pushing Marketing Language in Tech doc
Techwr-l
Learn from your developers
Conferences
Lynda.com (video tutorials)
Code academy (for python, html, others)
Blogs, news sites
4. HTML5
Scribe: Greg Urban
Top takeaways:
- HTML4 compare to HTML5 (HTML 4+1)
- new tags- a lot more tags
- attributes – many more
- cool features – audio tag, video tag, will pull in screen elements, including video player and IO player
- advantages: no more div soup
Notes:
HTML5: API, video tagging, looping video
new tag – Lots more – easier to understand
Recap of HTML development, interoperability usage of divs
HTML5 responsiveness depends on CSS, JavaScript
Data elements can move, flexible attributes not limited
efficient for video and audio tags
Advantages: no longer have to have a div
5. Metadata and categorization strategies
Scribe: Joan Lasselle
Top takeaways:
- can be simple or highly complex
- managed informally or managed by a specialist
- Helpful to have specifically trained specialist to help you get started
- Used to find topics/content (internal); use to help customer find data (external); use to track status of content
Notes:
Link with library science
The Accidental Taxonomist – introductory book , IA Institute
Few using today
Each topic – pick from a list
hard to come to a decision about what metadata
What do you want it for – to find topics in future to manage customer experience
Determined by queries
Most use to manage topics internally
Should not be redundant with the content
Keyword metadata – how do keywords relate to SEO
Metadata then keywords
metadata categories
Taxonomy – Define the context, what is the set of data you are working
who for
why do it
6. Job search techniques
Scribe: Ryan Young
Top Takeaways:
- Job boards – loud but low quality
- LinkedIn – higher quality, more work
- Referrals – highest quality, most work
- Make your own job – a lot of work
Notes:
Everyone in the job market
Job boards – loud but low quality – sponsored, there probably isn’t an 100$ fit for any job; the best fit is around 80%; sentient, articulate, fearless, and audience-aware
LinkedIn/Indexed/Simply Hired – higher quality, more work – costs $400 for 30-day to post a job, often just looking for future candidates (sometimes); listings != opportunity; better to know someone; LinkedIn is best – you know who is responding; “Post and pray”; LinkedIn is honest and refreshed often, others are dishonest or not trusted;
Referrals – highest quality, most work – companies like internal references better; most reliable and safest – internal referral bonuses are high;
Make your own job – a lot of work – find solutions to problems, consultants make more, even introverts can do it, and if not, get a “puppet” to be the face and voice
postings are “wish lists”
Ask people to prioritize job descriptions
Take job descriptions and create table comparing requirements to your skills
Teach yourself skills
Companies don’t post contract opportunities – once these go to an agency, the rate goes down
LinkedIn: use search + term – rich summaries and titles, use word cloud to get terms “writer” not “info developer”
Be forthcoming in summary about what you want to do to avoid marketing/social media jobs
Read job description that interest you: if you don’t have the skills, learn them. Start teaching yourself.
LinkSV: Search jobs by zip, search jobs here, contact companies via LinkedIn
Recruiters: self-interested sales people, who work for client – not you; won’t remember you; Short attention span: explain things to them using the job description. Tell them how much you need to earn.
Resumes need to clearly demonstrate how you map to job requirements. Needs to be clear why you are applying to this job
Project resumes sometimes seen as liabilities because they might be “mashs”
Employees want to see chronological resumes & escalating responsibilities
2-5 years/job is a good duration
Free conferences -> the trade show portion
Volunteer in tech writing organizations