Showing posts with label Documentation. Show all posts
Showing posts with label Documentation. Show all posts

Monday 2 May 2022

Useful Generic Resources from Microsoft - Miscellaneous

1. Microsoft Style Guide

Microsoft have an extremely useful Microsoft Style Guide for websites and apps to ensure the communication is clear and consistent.  It is simple to follow and makes understanding for customers easier.  The key takeaway for me is be consistent and "Be warm and relaxed, crisp and clear, and ready to lend a hand as appropriate for the context." Developer content - Microsoft Style Guide | Microsoft Docs 

For Ux Developers, the finalised messages is generally not available (or known) so it is good if they provide messages that they believe are correct that are "warm and relaxed, clear, and contextual", this allows for updates to be much easier for the final content reviewer.  

https://docs.microsoft.com/en-gb/style-guide

2. Fluent UI

Fluent UI Fluent UI - Get started - Fluent UI (microsoft.com) is useful to provide a consistent framework for Ux.

3. Frontend Bootcamp

Microsoft Days in the Web - Welcome

4. Kiota

Saturday 13 March 2021

APIM OpenAPI Specification Documentation Example within the Developer Portal

Overview:  I find document APIM contracts incredibly important and yet it's often very poorly done.  This post provide a simple YAML and JSON example that can be imported into APIM or any other gateway product for that matter.

The YAML file below can be imported into APIM and published to the developer portal.  The example provides a clear example on options and how an API should be documented.  Developers can see an example of the JSON to use when performing the PUT.  The developers can see more information of a property, for instance a passport number would be a certain length and rather than specifying and option free text string with no description, the developer would know that the property has to come in the correct format.

Simple Open API specification showing a single documented operation for a complex PUT object (YAML).

PB APIM Series:
Documenting you API in the Developer portal (this post)


Sunday 22 March 2020

My Solution Documentation Thoughts

It all depends on the project but this post outlines what I have found to be the best practices for documentation on projects. 

Documentation should not be an after thought but done effectively throughout the development of any project.  It helps clarify thoughts, communicate and should save time.  Documentation is generally poor as it is dumped on people that tend to write it from the wrong point of view.  For example, developers know the products or components but write the code from their point of view not necessarily effective to the enterprises understanding.

Documentation Should Cover

  • Overview & Start-up Documentation - Get the team with a common understanding.  I always like to have a Project Initiation Document (PID) that is kept short and up to date throughout a programme.
  • Architectural Design Decisions (ADD) - Get the technical people on the team with a common understanding.  Software Design Document (SDD)/architecture design document  - Description /overview.  High Level Design (HLD) & Low Level Design (LLD).  Architectural design decisions are stored in a Architectural Design Repository (can be a simple as a file server, I prefer SharePoint and a Wiki index).  
Possible Solution Architecture Information Architecture for holding SA docs 
  • Ensure documentation for: Solution Architecture, Dev processes, Support (wiki's), end user documentation, technical specifications (API's integration points), inline code must be simple and contain appropriate comments, and changelogs
  • Requirements - User Stories/Use Cases.  Get good clear requirements from the business.  This gives the team and architects, developers a clear idea/vision of what is to be built and often helps the product owner/stakeholders have a full clear agreed picture.  User stories are a great way to break apart large piece of functionality.  It's always a good idea to have functional (FR's also often referred to as Business Requirements (BR's)) and no-functional requirements (NFR's).  For me the best way to capture requirements is to use User StoriesFURPS is a way of categorizing requirements, useful to ensure adequate non-functional requirement areas have been covered.  I also like to use the old fashion MoSCoW (Must, Should, Could, Would) for prioritizing.  The most common mistakes I see in projects are requirements are:  1)  "Analysis paralysis" (very common in SDLC but more an issue with usage of SDLC than the methodology. 2) Gall's Law - stakeholders trying to put to much into a system from the start.  KISS/MVP - always opt for Keep it simple and only aim to deliver the minimum viable product.  Acceptance Criteria is a good way to validate when a User Story has been achieved.  Ideally a User Story should have less than 5 or 6 User stories.  If it has more, it is likely that the User story is too big and should be broken up into multiple user stories.  Weighted Shortest Job First (WSJF) is an Agile prioritizing system where you identify the highest priority items to do first.  Weighted matrix is another I have seen.  I also like an informal spend valuation that replies on effort/cost being already assigned.  Propriety Poker is also pretty common with multiple key stakeholders.  Stack ranking is also an easy option.
  • Code Documentation - Code comments & API Documentation/Swagger.  API's are often an architectural constraint in that you as a business may decide to everything needs to be implemented using REST API's.  APIM on Azure is a great tool for documentation and cross cutting concerns.  The developer portal documentation allows 3rd parties or other systems to securely access and documented API.
  • Performance And Testing
  • User/System Documentation - User Guides and knowledge bases. Reduce escalation or time to get end users working.  Support documentation, I use Wiki's, they are easy to use, update, once a problem is solved, it is easy to add a new wiki and all future support is much easier.  Wiki's are quick and easy and should be kept current, don't hold old decisions.  Wiki's are searchable and tag-gable.

Tip: I record a lot of decision and support using Snagit.  It's fast, brilliant for knowledge bases and end user training.  Considerably less effort than written documentation.
Note:  A lot of specific documentation is needed for legal and complaint/regulation, this can be pretty heavy but still best to understand the requirements and do it from day 1.
Thought: Technical Writer (can be a dev, BA, technical architect or a dedicate technical writer) - I believe the BA should also be the test lead on non-scaled Agile products.  They understand the requirement, therefore are best to understand the testing and write clear concise documentation in the form of test cases or acceptance criteria and user stories.
Tip: Use Grammarly and do documentation professionally.  Ensure your documentation is easy to follow, do not have spelling mistakes or grammar issues.  Lastly, consistent layout between different documentation writers must be consisted be this in code comments for full end user documentation.
Thought:  Write in present tense in an active voice, if forces people to look at the now and future.
Note: Companies have guidance and documents, ensure you know the format of documents and comply with company guidelines, this may be as simple as fonts and colours in your documentation to specific document formats such as TOGAF documentation standards.  Make it easy for your project with a little planning.
Thought:  Code comments - Naming should do most of the documentation, but complex logic or implementation decisions should be commented using the KISS principles.  Don't document exactly what the code says e.g. If (status=21)  // Apply logic if status is 21 // Rather us // Update the Customer Web Service if the users email address has change
Comments should not be used to delete code in case the developer needs it.  You have source control, delete the code.

Agile Documentation: Does not mean no or low documentation.  Agile documentation should be clean, concise and save time overall for the team members.  Essential documentation, don't over document or items that are obvious.  Prioritize documentation like we do in backlog evaluation.

Slack/Teams/Email:
I was a Slack evangelist, it is awesome for Agile projects especially for projects with people in different locations.  Well now I am a Teams guy.  It's awesome, simple and let's you remove so many dependencies.  If you haven't used it before and you have office 365, it's a "no brainer".  In 2 weeks everyone will love using teams.  I have had many dysfunctional teams that needed coaching, teams that document everything and in stand-ups you hear "I sent you that in an email".  The first thing I tell these teams is "email is not a defence", go tell or speak to the person.  These teams are To and CC nearly all there email.  I immediately enforce the rule To: means i want a reply CC means it's important to you.  If someone then sends and email that is CC'ed, I ask them why and they generally learn to use email conservatively.  I stopped a team several years back using email for 2 sprints to get them communication and trusting each other again.