Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 1 year ago.
Improve this question
Granted knowledge is best retained when put into practice, but as programmers I'm sure there's just too much information. Besides annotating your books, what other methods do you use for your own personal knowledge-base so you can have an easily accessible reference?
Do you create your own wiki or use software like wikidpad, or save them as plain text, bookmarks, pdf, web pages etc..? Or do you just treat google/SO as your giant knowledge-base and search only when required?
You may find this similar
https://stackoverflow.com/questions/10961/have-you-used-a-wiki-in-your-project-or-group, and of course this question can easily relate to non programmers as well.
Blog about it. That way you'll always have it no matter where you are, and that information gets shared with others.
I use Tiddlywiki to keep all of my development notes together, other than notes or handouts that I might get at a meeting that I want to keep. Those go into a folder for the particular project and I add a reference to them in my Tiddlywiki so that they don't get lost in the shuffle. I tag everything with a limited set of tags (rather than going overboard with the tagging, I have a set of 15 tags that cover the projects and categories I need) so I can get back to them quickly.
Works for me.
Otherwise, I blog about them as needed, use drive indexing for massive searching across lots of stuff, and keep a short daily summary of activities (1 or 2 lines) for better recall.
There are several solutions that I have seen people use successfully:
blog about it (as others have noted here)
maintain a Wiki (local or hosted)
keep it in a plain text file
use Backpack
use a hosted office solution (Google docs, Zoho)
email it to yourself in Gmail (yes, really :) well, makes stuff easily search able)
I personally use a TiddlyWiki (easy to use; very good search) which I carry around in a USB pen drive and which is also checked in to my SVN repository; and a small "notebook" (created from here) which fits neatly in a wallet, to jot down things when I am not near a computer.
Start a wiki.
ScrewTurn is what I use.
I've been storing my notes in Google Documents(google.com/docs). I've tried wikis but the cost of setup and maintenance hasn't been justified yet. I may need to look further into this option as my set of notes get larger.
Another thing to consider is ye olde programmer's physical notebook. Paper and pencil should never been underestimated in this digital age.
As far as personal Wiki software goes, I've been a big fan of VoodooPad for OSX. It's a nice self contained Wiki applications. No need to maintain a web server or have your Wiki hosted anywhere but your computer. Plus you can export into a variety of formats. It's very inuitive to use and can store just about anything you want.
It should also preserve syntax coloring if you were to extract a code sample (I don't have it in front of me so I cannot confirm).
I like Treepad for organizing notes. It's based around a tree structure, and each node can contain a text document, and have child nodes.
It's not particular designed for programming, but it's very easy to use.
org-mode for Emacs. I use it for planning work (short- and long-term), TODO items, random how-to notes (with clicky links to source files and URLs) — All in one single flat file. It has unicorns!
I use codekeep to store my code snippets
Occasionaly I store a few notes on google notes too
Mostly in a plain text on a flash drive, which is in the key ring along with keys from home. Plus eventually backups on the web site. This makes it available on any platform and in any place, wherever I go. There's still places without internet access you know.
Related
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 1 year ago.
Improve this question
I am unsure what to tag this under, but I'd imagine it's a question that's relevant to most developers.
Throughout my working day, I often come across snippets of information and knowledge that will come in useful again. These may be general coding examples, or else environment specific commands etc.
Typcially, I just store these in different text files, and then refer to these text files when I am in need.
However, this is awkward and difficult to search
One alternative I've considered is creating my own local Wiki and tagging such snippets under common tags, that I can easily search.
I'd be interested to know though how other developers manage such knowledge in a "pragmatic" way.
As above, TiddlyWiki seems like the best option here
I keep my notes in a combination of Evernote and Microsoft OneNote.
Evernote takes care of most of my note-taking while reading on the web. If you set up your notebooks in an organized way, and are diligent about tagging your notes when you create them, the built-in search makes that information available anytime, anywhere. Advantages:
Can group, sort and tag in as many ways as I want
Available on all my devices
Clipping articles and snippets is a breeze on Chrome with the
add-on
Simple interface
OneNote is brilliant when I'm working on my PC; it is more feature-packed than Evernote and the ability to free-form text and to paste in any other document is awesome. Wish it had the range of availability of Evernote; I wouldn't need anything else.
There is a very good knowledge management system at that is practising typing in the right keywords in google (or bing if you prefer).
I do it many times a day and have never had the urge to save anything, or even bookmark it, as it is easy enough to find it back if required, if not through your web browser's history by typing a similar query in google.
For progamming issues you may be better of using stackoverflow.com for your searches, but stackoverflow.com results are usually on top of your search result listing anayway.
I was using TreePad for that 6 or 7 years ago and it was great. The only problem was my computer crashed and I hadn't been backing up as I should have. So now I use Google Docs. The data isn't organized in the nice way that TreePad does, but I don't have to worry about backups and it has a search capability (although I have noticed a few glitches in the search before where it didn't find something I knew was there).
Closed. This question does not meet Stack Overflow guidelines. It is not currently accepting answers.
Questions asking us to recommend or find a tool, library or favorite off-site resource are off-topic for Stack Overflow as they tend to attract opinionated answers and spam. Instead, describe the problem and what has been done so far to solve it.
Closed 8 years ago.
Improve this question
I am looking for a really basic developer task/todo app or system. Are there any good ones out there? What are you using? All I need is a good overview and being able to add time and priority to my tasks.
I've found that a pen and dedicated project notebook works best for me. I maintain a priority by putting keeping a page for each priority level. If something changes priority I cross it off and move it to the new priority.
Time could be tracked with a written time estimate.
I've done the same thing using Emacs ORG mode, or a folder of .txt files, depending on how complex my project gets.
I just found what I was looking for. A really nice and simple todo app called Wunderlist. Thanks for all the answers though.
I write tasks on an index card. When I'm done with the story, I tear it up. Very satisfying. Of course, this means only working towards one thing at a time, which is a great discipline anyway.
I was just checking for one last week. Didn't want to go for a commercial app also hosted web apps like FogBugz had a limit on the free option of 2 users (3 would be smarter).
Most of the open source projects are bloated or in bad shape.
Finally settled on Project Pier and for a week it's been working out really well. The project is active but more importantly it does a fine job of what its main goals are.
EDIT for tasks/todos I highly recommend tasks jr
Pivotal Tracker
KISS: Emacs org mode if you are already an Emacs user, perhaps even if you are not; ff that doesn't suit you, Excel or another spreadsheet.
I use toodledo. It contains almost all imaginable functionality for a to-do list, while being simple:
Priorities
Contexts
Tags
Folders
Reminders
Ability to add new tasks by email
Ability to share tasks if necessary
Open API, which allows multiple third-party apps integration (a number of iPhone/Android applications, Outlook integration, browser plug-ins etc.)
Really basic system what I've used besides paper is to
% grep TODO *
Data.py: # TODO!
Data.py: # TODO normalize tag priorities so that Up/Down would work the best
If you like to TODO multilinely, give grep some context:
% grep -C 2 TODO *
Data.py- self.con.commit()
Data.py-
Data.py: # TODO!
Data.py- # Make the given tag go up or down in the list: find the next priority
Data.py- # in the sorted list of tags and set new priority
If you git,
% git grep TODO
works well and searches from the project files only.
In an IDE, I'd use its TODO features.
If your company provides you with Outlook, it's more than capable of managing a TODO list, along with alerts.
Failing that, a powerful text editor like VIM or EMACS will get the job done; they both have good plugins.
I know this has been answered already but Asana is an amazing, flexible to-do list with time tracking via integration with Harvest. Combined with Trello as needs arise, this is a 1-2 punch to the face of inefficiency. Hopefully this helps someone else.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
What are some good procedures to follow when handing a project to another developer, in cases of when the original developer will still be around for a couple of months to aid in the transition? Let's assume a medium-sized web application if a concrete example is necessary.
As a junior developer, I have gotten several projects assigned to me for maintainance that were written by others. I believe the easiest projects to continue are the ones where the code is clean and well documented (meaningful var names and formatting as well), the archetecture is relatively strightfoward, and the developer took some time to write some notes on the use of his components. In Java this would include class-level javadoc; in other languages it may include a header at the top of the source code.
Also, if the original developer is available and open to questions, it makes learning the archetecture much simpler - no puzzling out what he was thinking.
I've been on both ends. Taking over a code base and handing it off.
You should:
Identify areas that aren't completely
obvious. So, if you have a directory
called "xml" but all your flash
object get their data from
"flash/swfs/xml" you should document
that.
Identify parts of the database which
are no longer in use. If there are
tables that simply have no use
anymore.
Identify areas of concern such as
speed/performance of certain pages.
If you have some really backwards
logic on certain pages, explain why,
if it's not been commented in the
code directly.
Any third party vendors should be
identified along with their cost and
use on the site. So if you're using
a delivery network to stream your
flash videos, definitely let that be
known.
If you have pages still in the
project, but aren't being used
anymore, identify them, or simply
remove them.
If you know for a fact that your
database was poorly designed,
contains no constraints or indexes
and has no primary keys on many
tables, mention it. It will let the
new developer know they need to
optimize the database.
If you hardcoded e-mail addresses
within the code and didn't put them
in .config files, identify that as
well.
I'm sure there are more but there are things I wish were brought to my attention on a project I had taken over at one point.
If you have written your code from the start so that it is sensibly architected and fairly simple to understand, and provided adequate documentation, transitional problems should be minimal.
But training is always nice.
For anything that requires a build environment (certain compiler, 3rd-party libraries, opensource libraries, paths, etc.,), have the original developer sit down with the new developer, at the new developer's workstation, and walk through the process of making a simple change, committing to the source control, building, smoke test, etc.. Lots of times projects that are out of the mainstream may have odd procedures for testing, or they may come from an unfamiliar repository branch, may need a specific compiler version, libraries, etc.. Bugs may be tracked differently, it may require specific logins or endpoints for testing, etc.. By walking the new dev through the process, on their workstation, you'll uncover all of those issues, saving the new dev lots of frustration.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 3 years ago.
Improve this question
I have been looking for a collaborative tool for developing functional specifications. I am looking for the ability to:
Have multiple users contribute to the specification.
Provide some form of traceability, which could be done manually if needed.
Provide users with the ability to add comments and notes.
Upload and display Visio documents
Upload and display mockup screens using Balsamiq Mockup.
My initial impression is that using a wiki could be a good tool for this task. Does anyone have experience with using a wiki for creating functional specifications? What would be the pros and cons to using a tool like this as opposed to a requirements management tool?
Your input is greatly appreciated!
It's possible to do what you describe, to develop requirements in a collaborative way, in spite of using a wiki. Nothing about the wiki paradigm assists in this process.
I managed a wiki on the Zend Framework project to track proposals for components. They're still using it. Proposals are different from functional specifications, but the usage is similar enough to your question that I think this is relevant.
A wiki doesn't take care of itself. Unless you have someone responsible for managing it and making sure there is some structure and consistency, it quickly becomes a mess. The real-world analogy would be to hand each of your team a blank sheet of paper and tell them to write up their part of the requirements. Problems with this are:
Every contributor has to make up their own document structure, and write about different things in a different order. So it's impossible to compare one page to another.
There's no "index page" to organize all the disparate contributions. No one wants a page to "fall through the cracks," but in a wiki that's the default destiny of any page as soon as it's written.
There's no feedback loop to make sure the writing actually gets done.
The way to make it work is to apply some process to the project, and use the wiki in accordance with that process.
Give people the ability to create a new page in the wiki, but only through an interface that automatically links the new page into the right index.
Define a lifecycle for documents, so they are sure to be drafted, reviewed, and approved at the appropriate stages.
Provide a template for a new page. Provide the section headings that you need in each of these pages, and make part of the review process a confirmation that head section has been filled out adequately.
"What would be the pros and cons to using a tool like this as opposed to a requirements management tool?"
While it seems like a great idea, what you run into are people who can't and won't write.
People who can't write -- well -- can't write. They can't communicate with an email or a wiki or any medium outside voice.
Some people are "disorganized". Actually, writing is too linear and they don't think linearly.
Some people don't get the "write to your audience" and write stuff that's incomprehensible.
Sometimes you can't even figure out what they're talking about, much less what they're writing about. They talk in jargon or code. They don't know much but insist on being heard.
Some people won't write.
Some people refuse to make commitments. Even in a wiki where it can be retracted. They feel they must pre-discuss everything.
Some people are in the habit of doing everything by giving direction to someone else. They either don't write for themselves, or, they make people stand around in their office and listen to them talk and type.
Some people are generally toxic on any kind of project. They spring new requirements at the last minute. Their first response is "that will never work". They don't brainstorm well. When they say it work work, and you beg them for an improvement, they don't have one. They just know it won't work.
My experience is that only programmers can use a Wiki successfully. And only senior-level programmers.
N00bz don't have enough experience to sort out requirements from design from rumors and management fluff.
N00bz don't always have the language skills to write clearly. They may eventually, but one look at their Javadoc comments indicates that they're struggling with the "clarity" part of writing.
It's very appealing. I'm hoping for people to get better at using wiki's because I think it could have a lot of advantages over more traditional approaches where one person interviews everyone and writes things down. But it requires a level of confidence and skill in communication that few people seem to have.
Consider researching Fog Bugz. They tout themselves as the best of the
best for project management. Considering Joel's history I'd give them the
benefit of the doubt. They use a wiki in the way you've just described.
I would suggest signing up for the free trial, if you're serious.
Depending on the size of your project, buying it might be a very good
option.
At very least you could look at how they've structured it, or read the
forums for ideas on how to build your own stripped down version
Specialist tools help keep things on track and introduce a fixed work-flow. This is kind of the point, keeping things focused and functional. Using generic tools like a Wiki might be great for a bunch of programmers but introducing one for 'mixed-mode' work might be bad:
Things can creep and get off-track quickly
Communication can be lost in the medium
Look at things like Basecamp. They can be thought of as an applied wiki, or collaborative tool. A generic tool for specific purpose needs refining. I don't know if MediaWiki or others have enough customization to keep things clean and focused.
Maybe gather the requirements for your requirements management tool (recursive I know) and what aspects (communication aspects) you can take from the wiki culture and an open-communication mindset. If neither requirements management tools or wikis fit the bill, look at building one. Might be the next big thing. It feels like saying Could I use a wiki instead of Bugzilla?
A fixed work-flow webapp for requirements management with an open-communication emphasis that allows people from many roles to see and understand might be good!
We have used TWiki and now FosWiki in that context. There are many things one gets for free (version control, access control, Web-base access, searches, remote management, security patches, ...). In a few minutes, one can define:
a table defining requirements attributes,
which creates interactive forms with field selection and validation (where you can also document discussions and rationales, embed images, attach documents, link to other requirements...),
and then queries on these "requirements" and show them as tables that can be sorted, filtered, printed, reported against, etc. (e.g., http://jucmnav.softwareengineering.ca/ucm/bin/view/ProjetSEG/JUCMNavRequirementsVer2).
Obviously, one can easily use hyperlinks and Wiki links along the way. FosWiki also has features that can be used to enforce specific workflows, if needed. It is also easy to support forms for use cases and other paradigms (we have done this in the past, and that works generally well).
Wikis such as FosWiki are extensible and one could develop further modules for addressing weaknesses related to traceability management and impact analysis, table-based modifications of requirements, overall packaging, etc.
As a middle ground between a free-form wiki and a requirements management tool, consider using a structured wiki like Foswiki. I haven't done any formal requirements management (with a wiki or otherwise), but I have used TWiki (the predecessor to Foswiki) for other tasks, and it permits you to define a workflow, form fields, and so on as you need them, while keeping the flexibility of a wiki when you don't need a formal structure.
I agree with all (most) of the people above - use of a wiki may sound ok, but wiki's are meant to be present information and be updated as needed, not to be used as an interactive project management tool. I would strongly suggest SmartSheet (I'm a strong advocate of the product) - it provides a spreadsheet like interface where you can store multiple files per row/task, send out automated updates to users and maintain specification revisions...
The other approach could be the use of Google email, docs and calendar - a free friendly way of team interaction....I would shy away from issue/bug tracking tools for project management - they tend to have differ on focus: PM tools on the entire project/resource/timeline and Issue tracking tools for specific entered issues....
This may be a bit old now, but I am currently using Atlassian's "Confluence" and it's been great. I currently work as a UX engineer playing the role of "Product Owner" within an Agile process. I can document requirements for discrete interfaces, allow for multiple users' feedback and comments, and intertwine each interface with other interfaces within a larger context (e.g. user story). Everything is very dynamic and template driven. It's suiting my current needs very well.
Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 5 years ago.
Improve this question
Back in the days of Unix, you couldn't even close a software without reading the man page first. Then came Mac and Windows with consistent menu layout and keyboard shortcuts, but you still saw paper user manuals shipped in the shrinkwrap box, which described each and every single operation possible in the app. After the Internet, help files became html documents.
Nowadays with Web 2.0 applications, you hardly see the Help. Even if it's there, they simply describe some specific tasks. In other words, the apps are relying more on the common sense or don't-make-me-think factor of the user base.
Years ago Microsoft came up with a concept called Inductive User Interface, which basically tells programmers to put in instructions on the apps itself, but I am not sure how popular that idea is.
Are help files, user manuals, and context sensitive online help with F1 key dead? Have I failed if user could not find out what to do from the UI? If not, what degree of help should I provide? (both for desktop and web app)
EDIT: How does documentation/help file mesh with agile development methods? For example, should the developers think twice before UI changes that may obsolete a bunch of screenshots?
Three notes on help:
F1 / stand-alone context-sensitive help was always doomed. It was hidden by default, and so the people who most needed it were least likely to read it. There was hope at one time that we would be able to train users to always hit F1 when they ran into trouble, but too many applications without useful context-sensitive help... combined with too many bizarre help interfaces... pretty much killed this.
Manuals are as important now as they ever were. Not so many printed manuals anymore, but online manuals are better than ever. The proliferation of wiki-as-a-manual systems has helped here, reducing the up-front cost of creating good online documentation. Of course, plenty of people just don't read...
The beauty of using web pages as an application interface is that you can combine useful context-sensitive help with the UI, removing the barrier for novices and others who otherwise couldn't be bothered to look for relevant information when they get stuck.
Of course, there are still plenty of apps, even online apps, designed with obtuse interfaces and a tiny little help icon in a corner somewhere, presumably hoping that the latter mitigates the former. Pity them.
No way. You look at the amount of documentation and training and marketing expenditure even MS puts up.. you'll get your answer.
Try using someone else's product, and you will learn the true value of documentation - I'm learning Godiagrams right now.. :)
So I can say without a doubt.. NO and it never will.. no matter how intuitive user interfaces get.. beyond a certain size, you will need help and training. But by understanding the user and what he needs to get done, you could design it such that the time he/she needs to learn the system to do his/her routine tasks is minimal.
Have I failed if user could not find out what to do from the UI?
If not, what degree of help should I provide? (both for desktop and web app)
They should be able to use your your app to do basic things from the UI. eg say for an image editor, they should be able to create a new image, and draw some lines then save it just by looking at the UI.
This is best done by following common layouts (like having new, open and save under file in the menubar, and using the standard open and save dialogs).
The same goes for webapps, people exspect to be able to do the basic stuff without having to read the docs, but for more advanced features people will still read the docs. (eg most pople will read the docs for say BB code, or markdown at least sometimes, but they expect to be able to post without having to know them)
Are help files, user manuals, and context sensitive online help with F1 key dead?
They still have their place. People will use them to learn about how to best use various features, for example markdown or bbcode, or how to use filters to get certain effects in an image editor.
I've been incorporating context-sensitive screencasts into my applications. I've found this helps non-technical users grasp the application quickly, without asking for live help.
The Idiot/Dummy books must be doing quite well. Imagine if the standard application help was as good as those books. The standard F1 help for a lot of apps is just awful.
Is help dead? No, but some of it should be taken out and shot.