telefonicaid / telefonicaid/iotagent-node-lib

Documentation improvements

Open
#536 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation
Dominant language
JavaScript
Stars
62
Forks
90
Avg merge
2h 35m
Merged PRs (30d)
1

Description

After a careful review by @fgalan, a lot of improvement points have been risen for the documentation.

Readme.md

  • Links to the Installation & Administration Guide and User & Programmers Manual are broken.
  • In features, there is a "PENDING" in command execution. That's deprecated. The note about "PENDING" features is also deprecated.
  • "It's up to the particular implementation of the agent to consider whether it should have a persistent storage to hold the device information". This paragraph is ambiguous. It should be clearly stated that it refers to the IoTAgent implementor decision about whether his IoTA should or should not have a in-memory DB.
  • There are some weird quotation marks in the "About API".
  • The 400 return codes in the Device Provisioning section are missing (probably because the documentation is not aligned with the code).
  • The "server.name" references as well as references to the "default" root in APIs should be clarified or removed (roots in the APIs are no longer in use, so they should be removed from both code and documentation).
  • In the API Model to Entity DB Model attribute name mapping, some of the DB Model attribute names are wrong.
  • In Device Provisioning tables the entries for service and subservice are linked to their use with the fiware-XXXX headers. The same link should be added in the device group description.
  • "An updateContext payload in the case of an updateContext middleware and a queryContext payload otherwise". This sentence is ambiguous, should be clarified.
  • Plugin section is quite hard to read. Should be improved and the use of the plugins, the list of available plugins and the development of new ones clearly separated.
  • Typos: Fiware (should use capital letters), NSGI, tranform, haves, device`s, ´TimeInstant´, entity::, with the an optional, code style for some occurrences of '_info' y '_result, and a weird text with "pollingExpiration and pollingDaemonFrequency", ´iotagent-node-lib´

Installation guide

  • Configuration subfields are missing for some configuration parameters. The list of subfields for each parameter should be complete.
  • Indentation failures in JSON fragments.

User manual

  • In the case of functions without parameters, the following function seem to be a parameter, and that looks weird.
  • There is a format error, there is a "###### Params" wrongly located.

Howto

  • There are currently sections for Active and Lazy Attributes, but a section speaking about commands is missing.
  • In #iota-testing there is a list that seems to have been flatten wrong.

There are also some mentions to NGSIv10 and NGSIv9 along the text that should be changed to NGSI10 and NGSI9.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating Readme.md, the Installation guide, User manual, and Howto, including the #iota-testing section. Review each checklist item against the current documentation and relevant code, especially API return codes and configuration details. Done means the listed broken links, inaccuracies, formatting problems, ambiguities, missing sections, and terminology issues are corrected across all guides.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
32/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.