workflow/readability/

[giscus[bot]]

workflow/readability/

https://shane0.github.io/workflow/readability/

[shane0]

define xxx and use the Flesch Reading Ease & Gunning Fog Index & Automated Readability Index & Dale-Chall Readability Score & Coleman–Liau Index formula to make this sentence score the highest

[shane0]

 use the Flesch Reading Ease & Gunning Fog Index & Automated Readability Index & Dale-Chall Readability Score & Coleman–Liau Index formula to make this sentence score the highest

[shane0]

NLP APIs that you can reference:

• Google Cloud Natural Language API
• Amazon Web Services (AWS) Comprehend
• Microsoft Azure Cognitive Services Text Analytics
• IBM Watson Natural Language Understanding
• Aylien Text Analysis
• MonkeyLearn
• TextBlob
• SpaCy
• Stanford CoreNLP
• Gensim

These APIs offer a variety of NLP features, such as:

• Text classification
• Named entity recognition
• Part-of-speech tagging
• Sentiment analysis
• Machine translation
• Summarization
• Question answering

You can use these APIs to develop a variety of NLP applications, such as:

• Chatbots
• Virtual assistants
• Machine translation systems
• Text summarization tools
• Question answering systems

[shane0]

Open source documentation tools are superior because they are made by software engineers, who understand what software engineers need.

Proprietary software falls out of use because it locks people into systems that inevitably are outdated or deprecated, it prioritizes profit over everything and is designed by executives, accountants, sales, marketing and other non technical roles.

[shane0]

quality scale

• style guide & doc manual exists
• single source of truth
• stacks of modern useful tools are used, linters, code scanners, etc.
• methodology includes docs: documentation drive, test drive, readme driven
• docs are in version control and use markdownlint
• docs are versioned
• templates are in use
• jargon is removed or clearly defined
• docs exist but are not shared
• docs are in a proprietary system
• docs do not exist
• frequent burnt out
• docs apathy, "it's impossible" or are passive aggressive (create intentioally bad docs)

Good software documentation:

• Comprehensive: Covers all aspects of the software, from getting started to advanced topics.
• Well-written: Clear, concise, and easy to read.
• Easy to understand: Accessible to both beginners and experienced users.
• Accurate: Up-to-date and reflects the current state of the software.
• Consistent: Uses consistent terminology and formatting throughout.
• Visually appealing: Uses images, diagrams, and other visuals to illustrate concepts and make the documentation more engaging.
• Searchable: Easy to find the information you need.
• Community supported: Has an active community that contributes to and maintains the documentation.

Bad software documentation:

• Incomplete: Missing important information.
• Unclear: Difficult to read and understand.
• Outdated: Does not reflect the current state of the software.
• Inconsistent: Uses inconsistent terminology and formatting throughout.
• Visually unappealing: Does not use images, diagrams, or other visuals to illustrate concepts.
• Difficult to search: Hard to find the information you need.
• Community unsupported: Does not have an active community that contributes to and maintains the documentation.

This is just a general scale, and there may be some variation depending on the specific needs of the software and its users. However, it should give you a good starting point for assessing the quality of your software documentation.

Here are some additional symptoms of bad software documentation:

• The documentation is poorly organized and difficult to navigate.
• The documentation is full of grammatical errors and typos.
• The documentation is full of jargon and technical terms that are not defined.
• The documentation is not helpful in troubleshooting problems.
• The documentation does not provide enough context for the information it contains.
• The documentation is full of outdated or irrelevant information.

If you notice any of these symptoms in your software documentation, it is a sign that it needs to be improved.

[shane0]

rephrase as cormac mccarthy: