Developing documentation for open source projects

Don’t let a lack of documentation drag your project down

Poor or missing documentation is one of the key challenges for open source projects. It’s very difficult for an open source project be successful without documentation that describes its architecture, or explains how to use the software.

Many developers don’t like writing documentation. They have to deal with the “curse of knowledge”. This means when we know something, we find it hard to imagine what it was like not to know it. However, documentation is essential work.

Don’t worry if you don’t have the time or skills to do it in-house. Cherryleaf can lead your documentation projects and sprints. We can also provide Technical Authors to write the online Help, onboarding screens, embedded Help, or a knowledge base for your product or service. Let’s start to solve your problem: use the “Contact Us” button below to tell us about your situation.

Our services

Leading open source documentation projects and sprints

Our work can include:

  • Planning a documentation project or a documentation sprint
  • Structuring the content
  • Writing – writing content and delegating writing tasks to others the writing team
  • Project management
  • Managing reviews and the editing process
  • Publishing the content
  • Identifying and celebrating success

Leading writing workshops

The workshops can cover these topics such as:

  • Identifying a list of topics that need to be created or updated
  • Prioritising tasks
  • Allocating the work
  • Information design
  • Style and tone guidelines
  • Best writing practices
  • How to use the authoring tools
  • Publishing workflow
  • User-centred writing approaches
  • Editing and reviewing
  • How to maintain the content in the future

Writing online (web) Help pages

By online Help pages, we mean Help that’s delivered as a set of HTML files. These can be in a knowledge base, a Help section, or linked to your support ticket system. This type of Help is used for Software as a Service, other web-based applications, and mobile apps. It can also be used for desktop applications.

Developing onboarding screens/Walkthroughs

Onboarding screens introduce the application to the user, and demonstrate what the product does. Cherryleaf can help you create your onboarding screens – getting the content and the design right for your product and your audience.

Writing UI text and Embedded Help

UI text and Embedded Help places the Help information in the application screens. The user doesn’t need to leave the current screen to find the answer to their questions.  We write the Help in text or Markdown format, which is then compiled with the application code files.

Creating printable versions

We can also create print versions in PDF, Word, or another printed form.

Creating API documentation

See Cherryleaf’s API documentation writing services

 

Our approach

One source, many outputs

We often use a single sourcing and topic-based authoring approach. This means you can publish content to a range of different configurations and outputs. You can also provide a more personalised experience for the user.

Our work involves:
  • Making any existing content clearer and easier to use.
  • Writing new content for you, where it's missing.
  • Organising the content in ways that make it easy for people to find the information they need.
  • Setting up systems so that information isn't left to stagnate and get out of date. Depending on your needs, these systems can:
    • Deliver the content in different formats.
    • Enable you to re-use chunks of text in different publications, and in different contexts for users:
      • Subsets delivered for different outputs.
      • Personalised content for different job roles, location etc.
      • Create it once, and re-use it multiple times.
    • Automate the exchange of content with other systems, so others can use your content in their outputs.

Have a preferred authoring tool or working method?

We can use a writing process that suits your workflow and technologies. Cherryleaf works with a wide range of authoring tools, including Markdown-based applications.

 

Useful information on creating great documentation for open source projects

Selected posts on technical writing from the Cherryleaf Blog

The ROI of user documentation: you could break even if you avoided 3 support calls per week 

How to create online Help topics that are editable by clients

Free guides – Technical writing

Cherryleaf’s online cost reduction calculator

Why the marketing funnel and technical writing are changing

Getting customers to answer their own support questions

Decision making guide: Do I need a Technical Author?

Featured documentation episodes from the Cherryleaf Podcast

Zendesk and Knowledge Centred Support

“Our boss wants us to consider the idea of merging our Help content and our “Knowledge base” which is like articles/support troubleshooting etc. Whether this is our content going into the knowledge base or vice versa, we’re not sure in terms of direction. Do you have any opinions on merging article-based content like this into a Help Authoring tool or Help content into a “normal” website like that?”

Docs Like Code

Interview with Anne Gentle, author of Docs Like Code and Product Manager at Cisco.

Every Page is Page One

Interview with Mark Baker, author of Every Page is Page One.

 

Contact us

Need help in writing the documentation for your open source project?

Complete the contact form below. Don’t worry if you don’t know the answers to all of the questions.

We will contact you to discuss your situation and requirements.

You can always phone or email us, if you prefer.

* Required

Your name (* required)

Your email (* required)

Your telephone number

Your location *(required)

Tell us a little about your requirement *(required)

Can you tell us how much content is needed?
(Or, for existing content, how much is there?)

Tell us a little about your audience, timescales and budget.

How would you like Cherryleaf to help you?

We'd love to email you links to useful articles and news on developing content. We'll always treat your details with the upmost care, following the EU's GDPR consent rules.
(required)

No, I don't want to receive updates.Yes, I'd like to receive updates.